home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1995 November / EnigmA AMIGA RUN 02 (1995)(G.R. Edizioni)(IT)[!][issue 1995-11][Skylink CD].iso / earcd / program / gcc / gcc270-r.lha / gnu / README-2.7.0 < prev   
Text File  |  1995-08-21  |  37KB  |  978 lines
  1. Short: gcc v2.7.0 - C/C++/ObjC Compiler set for AmigaDOS
  2. Type: dev/gcc
  3. Uploader: phb@colombo.telesys-innov.fr
  4. Author: phb@colombo.telesys-innov.fr
  5.  
  6. This is the AmigaDOS 2.7.0  GNU C/C++/Objc compiler.
  7.  
  8. The GNU C compiler is free software.  See the file COPYING for copying
  9. permission. PLEASE be sure to read README file enclosed in gcc270-readme.lha
  10. FIRST.
  11.  
  12. ===============
  13. How to get help
  14. ===============
  15.  
  16. There's an Amiga-GCC mailing list running in Finland, read README-LIST file.
  17. This is the preferred place to ask for help since I'm on this list and
  18. every GCC developers also, libnix & ixemul authors, etc...
  19.  
  20. Short: send an email to listserv@lists.funet.fi, and put in body:
  21.     subscribe amiga-gcc-port your_first_name your_last_name
  22.  
  23. (insert your own first name and your own last name above)
  24.  
  25. Otherwise you can contact me at:
  26.  
  27.     Philippe BRAND
  28.     Fidonet: Ramses The Amiga Flying BBS 2:320/104.0
  29.     Email:   phb@colombo.telesys-innov.fr (ONLY for personal email).
  30.     WWW:     www.telesys-innov.fr
  31.     Ftp:     ftp.telesys-innov.fr:/pub/amigados-gnu
  32.              or /pub/incoming/uploads for uploads.
  33.  
  34. Note: I'll forward any question to this mailing-list, but please use it
  35. directly, except when you send files, in this case send them to my ftp site.
  36.  
  37. Note 2: ftp.funet.fi mirrors my amigados-gnu tree. Using ftp.funet.fi is
  38. preferable as they have much more bandwidth (/pub/amiga/gnu).
  39.  
  40. ============
  41. Requirements
  42. ============
  43.  
  44. - Systems:
  45. Any Amiga (ranging from A1000 up to A4000/40, including CD-32 & SX-1) will
  46. run AmigaDOS-GNU utilities.
  47.  
  48. - Memory:
  49. A minimum of 4 MB of free memory is needed in order to compile small/medium
  50. projects. More memory will be needed for large projects, such as recompiling
  51. GCC itself.
  52. Gigamem is known to work with GCC so *maybe* less memory will work. But in
  53. this case, you'll need an MMU equipped Amiga (A3000,A4000/40, etc...).
  54. VMM (Public Domain Virtual memory manager upto version 3.0, Shareware from
  55. 3.1 and up) is also known to work with GCC.
  56.  
  57. - OS:
  58. Starting from version 2.5.x, 1.3 systems are not longer supported.
  59. GCC runs fine on all other systems, starting from 2.04 up to 3.1 (40.68).
  60.  
  61. - Disk Space;
  62. An installation of GCC requires the use of a hard disk. Approximately 10 MB
  63. is required at present to install the compiler and utilities required to use
  64. it. In addition 3 MB is required for the Commodore Developer Kit, which is
  65. required to be able to compile AmigaDOS specific programs.
  66.  
  67. ==========================
  68. What's new in this release
  69. ==========================
  70.  
  71. 2.7.0
  72.  
  73. - Read FSF NEWS-2.7.0 file included.
  74. - As always, generic bugs fixed (see Changelog in GCC sources for details).
  75. - FSF listing shell script suppressed.
  76. - new as/ld/size/nm/ranlib using BFD, made by Raphael Luebbert
  77. - as fixed, used to generate some 020 instructions while in 68000 mode.
  78. - all programs recompiled using 2.7.0 compiler.
  79. - new inlines headers.
  80. - new compiler options: -mstackcheck and -mstackextend, to respectively
  81.   implement stack checking and auto-stack growing into GCC compiled programs.
  82. - resident option is now fixed.
  83. - new ixemul library, v41.1 (complete distribution can be found on Aminet
  84.   site).
  85. - new libnix, v1.0 (sources can be found also on Aminet sites, in libnix
  86.   archive).
  87.  
  88. This release is dedicated in memory of Pierre Carette.
  89.  
  90. =================================
  91. What was new in previous releases
  92. =================================
  93.  
  94. 2.6.3
  95.  
  96. - Read FSF NEWS-2.6.1 file included.
  97. - As always, generic bugs fixed (see Changelog in GCC sources for details).
  98. - q_anote package replaced by FSF listing shell script, need awk.
  99. - new as/ld/size/nm/ranlib, made by Raphael Luebbert
  100. - new environent variables GCCPRIORITY and GCCSTACK, see below.
  101. - all programs recompiled using 2.6.3 compiler.
  102. - mit2mot & mot2mit, convert asm syntax between Motorola and MIT syntaxes.
  103. - all programs hold AmigaDOS compatible $VER string.
  104.  
  105. 2.6.2
  106.  
  107. - internal release only.
  108.  
  109. 2.6.1
  110.  
  111. - Read FSF NEWS-2.6.1 file included.
  112. - As always, generic bugs fixed (see Changelog in GCC sources for details).
  113. - new option -priority in gcc allowing process priority setting.
  114. - new specs file, inlines/protos and libamiga done by Gunther Nikl. See note
  115.   below.
  116. - new libnix version by Matthias Fleischer & Gunther Nikl.
  117. - new ixemul version by Raphael Luebbert.
  118. - stripc program to strip all uneccessary stuff from headers by Chris Metcalf,
  119.   submitted by Lars Hecking.
  120. - q_anote, annotate assembly files mixing C source code, submitted by Walter
  121.   Harms (Walter.Harms@arbi.informatik.uni-oldenburg.de), written by
  122.   Mike Albaugh (albaugh@agames.com). See note below.
  123. - new assembler, as-2.5, using new BFD (Binary File Descriptor), made by
  124.   Raphael Luebbert.
  125.  
  126. 2.6.0
  127.  
  128. - Read FSF NEWS-2.6.0 file included.
  129. - Extensive internal compiler bugs fixed (see ChangeLog in GCC sources for
  130.   details), tons of bugs fixed for C++ support.
  131. - ld changed (see note for ld below).
  132. - new ixemul.library, with optimized versions for accelerated Amigas, see
  133.   README-ixemul & ixemul.guide for more informations.
  134. - new C library (libnix) disabling use of ixemul.library for generated
  135.   programs (best use for AmigaDOS specific programs). Full ANSI compliant,
  136.   see README-libnix & libnix.guide for more informations.
  137. - revised inline headers in accordance with new ixemul.library.
  138. - libamiga.a is now distributed with GCC-2.6.1.
  139. - as v2.3 is included, along with a macro-assembler (gasp).
  140. - stderrfix.o (see below) patch applied.
  141. - Upgrade to libg++-2.6.
  142. - GCC now supports $VER string for AmigaDOS version compatibility.
  143.  
  144. 2.5.8
  145.  
  146. - Read FSF NEWS-2.5.8 file included.
  147. - ld behaviour over symbols changed (see note below).
  148. - added flavours so that linker will take appropriate libraries according to
  149.   gcc options (m68020 libraries/baserel libraries, etc...).
  150. - gpc (GNU-Pascal) v1.03 added.
  151. - all utilities recompiled with GCC-2.5.8.
  152. - plain 68000 and 68020+68881 versions of all binaries available.
  153. - More internal compiler bugs fixed (see ChangeLog in GCC sources for
  154.   details), some for C++ support.
  155. - GCC-Install script fixed by Claus Deckhut (to be used with full
  156.   distribution).
  157. - Upgrade to libg++-2.5.3.
  158. - trace.c updated by J. Hoehle to avoid buffer overflows.
  159.  
  160. 2.5.7:
  161.  
  162. - Read FSF NEWS file included.
  163. - More internal compiler bugs fixed (see ChangeLog in GCC sources for
  164.   details), a lot for C++ support.
  165. - Fred Fish seems to have finally found an annoying bug which prevented
  166.   to compile a resident version of GCC, or to compile resident programs. But
  167.   don't try it anyway 'cause there's still lack of library support as for now.
  168. - Man command now works, this one was my fault (well in fact like others ;-),
  169.   fix done by Tom Haiko.
  170. - Infoview works also, it was an internal path problem.
  171. - libamy.a HAS TO BE RENAMED to libamiga.a because new ld won't find libamy.a
  172. - upgrade to new C++ library v2.5.1.
  173.  
  174. =======
  175. Authors
  176. =======
  177.  
  178. GCC v2.2.2 port:   Markus Wild
  179. GCC v2.3.3 port:   Markus Wild
  180. GCC v2.4.5 port:   Philippe Brand, Lars Hecking, Fred Fish
  181. GCC v2.5.0 and up: Philippe Brand, Fred Fish, Leonard Norrgard
  182.  
  183. Ixemul.library:    Markus Wild (original programming),
  184.            Leonard Norrgard (vinsci@nic.funet.fi),
  185.            Raphael Luebbert,
  186.                    Stephan Isthesin.
  187. Libnix:            Matthias Fleischer (fleischr@izfm.uni-stuttgart.de) and
  188.            Gunther Nikl (gnikl@informatik.uni-rostock.de)
  189. Installer Prog:    Jochen Wiedmann (jochen.wiedmann@zdv.uni-tuebingen.de)
  190.  
  191. Thanks to all amiga-gcc-port mailing-list users for their reports and support
  192. for a better AmigaDOS-GCC and documentation.
  193.  
  194. =======
  195. Sources
  196. =======
  197.  
  198. These archives should contain everything necessary to get you going, they
  199. don't include sources for all tools (have a look at end of paragraph).
  200.  
  201. As stated by Richard Stallman of the FSF:
  202.  
  203. "The GPL says that any distribution of binaries must contain either the
  204. source code or a written offer to supply source code (see the GPL for
  205. details of what is required)."
  206.  
  207. If you're interested in the sources required to rebuild GCC, get the
  208. gcc270-src.lha, which hold sources for GCC. Those archives should be stored
  209. either the same ftp site you got this binary distribution from (if they're
  210. not, tell the manager of that ftp site, as this is a requirement of the
  211. GNU Copyright LICENSE), either at ftp.gnu.ai.mit.edu:/pub/gnu, either on
  212. Ramses BBS (phone numbers listed below).
  213.  
  214. If you have those archives, you can skip to next paragraph. If you have
  215. original FSF sources, you'll have to apply the GCC patch-file in src-patches/,
  216. and configure for `amigados'. Please note that you should have at least 40 MB
  217. left or your HD and 8 MB of memory minimum in order to rebuild GCC up to stage
  218. 3. An accelerated Amiga is welcome, as it took me 4,5 hours to generate a
  219. single pass. So 3 passes makes 4,5 x 3 = 13,5 hours.
  220.  
  221. Sources for other tools only included as binaries are available separately
  222. in self-contained archives, usually having their name into the archive-name.
  223.  
  224. File                What
  225.  
  226. gcc270-src.lha            C/C++/ObjC compiler sources & diff file
  227. libnix-1.0.lha            libnix sources and binaries
  228. ixemul-41.1-src.lha        ixemul sources and libraries
  229. binutils-1.8.x-src.lha        Sources for ld
  230. binutils-2.5.2-src.lha        Sources for ar/ranlib & diff file
  231. make-3.74-src.lha        make sources & diff file
  232. gdbm-1.7.3-src.lha        Sources for gdbm & diff file
  233. patch-2.1-src.lha        patch sources, needed to apply diff files
  234. sed-2.05-src.lha        sed sources & diff file
  235. gawk-2.15.5-src.lha        GNU awk sources & diff file
  236. diffutils-2.7-src.lha        diff utility sources & diff file
  237. fileutils-3.11-src.lha        file utilities sources & diff file
  238. sh-utils-1.12-src.lha        shell utilities sources & diff file
  239. textutils-1.11-src.lha        text utilities sources & diff file
  240. findutils-4.1-src.lha        find sources & diff file
  241. grep-2.0-src.lha        grep sources & diff file
  242. bison-1.22-src.lha        bison (yacc replacement) sources & diff file
  243. flex-2.4.7-src.lha        flex (lex replacement) sources & diff file
  244. texinfo-3.1-src.lha        texinfo (includes makeinfo) sources & diff file
  245. gzip-1.2.4-src.lha        gzip sources & diff file
  246. tar-1.11.2-src.lha        gtar sources & diff file
  247. cpio-2.3-src.lha        cpio sources & diff file
  248. gdbm-1.7.3-src.lha        database manip. library sources & diff file
  249. termcap-1.2-src.lha        termcap library sources & diff file
  250. libm-5.6-src.lha        BSD mathematic library sources & diff file
  251.  
  252.  
  253. NOTE:
  254. All sources archives are Amiga ready, and Amiga specific diff file located
  255. in 'amiga' directory. To recompile a tool, just run a 'configure amigados'
  256. then a 'make'.
  257. Exceptions are libnix and ixemul which have their own archives, both binary &
  258. sources.  On Aminet sites, libnix & ixemul in /pub/amiga/dev/gcc.
  259.  
  260. =====
  261. Where
  262. =====
  263.  
  264. **** All GNU sources & binaries are available on:
  265.  
  266. - ftp.telesys-innov.fr, primary Amiga-GNU FTP site, and its mirror ftp.funet.fi
  267.   which is MUCH faster than my own site. Please use it at first choice.
  268.     in /pub/amigados-gnu
  269.  
  270. - Aminet sites (wuarchive.wustl.edu and mirrors such as ftp.luth.se)
  271.     in /pub/amiga/dev/gcc
  272.  
  273. - Ramses The Amiga Flying BBS  +33-1-45845623  USR V.everything   2400-33600
  274.                                +33-1-53791199  USR V.everything   2400-33600
  275.                                +33-1-53791200  USR Sportster V32b 2400-14400
  276.                                +33-1-53791219  USR V.everything   2400-33600
  277.  
  278.     in Topic "Development", Area "Gcc" (File Area 156).
  279.  
  280. - FreshFish CDs from Fred Fish           Amiga Library Services
  281.     in :GNU/bin, :GNU/src, :GNU/lib dirs.  610 N. Alma School Road, Suite 18
  282.                        Chandler, AZ 85224-3687
  283.                        USA
  284.                        FAX:    (602) 491-0048
  285.                        VOICE:  (602) 491-0442
  286.  
  287. **** GNU source code is available on:
  288.  
  289. - same FTP site you've taken these archives
  290.  
  291. - gnu.prep.ai.mit.edu 18.71.0.38
  292.     in /pub/gnu
  293.  
  294. - Ramses The Amiga Flying BBS
  295.     in Topic "AmigaUnix/Unix/Linux/NetBSD", Area "Gnu Source Code"
  296.  
  297. - FreshFish from Fred Fish
  298.     in :GNU/src
  299.  
  300. ======
  301. Layout
  302. ======
  303.  
  304. GCC-2.7.0 is split up into 15 archives:
  305.  
  306. gcc270-readme.lha    holds readmes files (include installation notes).
  307. gcc270-base.lha         basic GCC distribution, hold necessary files.
  308. gcc270-inclib.lha    headers and libraries.
  309. gcc270-c.lha        C compiler.
  310. gcc270-c-020.lha    68020 version of C compiler.
  311. gcc270-c++.lha        C++ compiler, headers and libraries.
  312. gcc270-c++-020.lha    68020 versions of C++ compiler.
  313. gcc270-objc.lha        Objective-C compiler, header and libraries.
  314. gcc270-objc-020.lha    68020 versions of Objective-C compiler.
  315. gcc270-doc.lha        GCC AmigaGuide(tm) documents & manpages.
  316. gcc270-utils.lha    Useful utilities needed for development.
  317. gcc270-utilsdoc.lha    Utilities documentation (guide & manpages).
  318. gcc270-texi.lha        All Texinfo documents.
  319. gcc270-diffs.lha    Diff files for all binaries.
  320. gcc270-src.lha        Source for GCC-2.7.0 plus diff file.
  321.  
  322. Name            What                    Where    
  323. ----            ----                    -----
  324.  
  325. COPYING            GNU LICENSE, read!!            All archives
  326. COPYING.LIB        GNU LIBRARY LICENSE, read!!        All archives
  327. README-2.7.0        this file                All archives
  328. NEWS-2.7.0        What's new in GCC-2.7.0            gcc270-base
  329. Installer        Commodore installer utility        gcc270-base
  330. GCC-Install        Installer script to configure GCC    All archives
  331. envarc/            global environment variables you should
  332.             have set when using this programming    gcc270-base
  333.             environment
  334. include/        non-Amiga specific C/C++ headers    gcc270-inclib
  335. os-include/proto    Amiga specific protos headers.        gcc270-inclib
  336. os-include/inline    Amiga specific inline C headers. Add    gcc270-inclib
  337.             Commodore headers!!        
  338. os-lib/            Amiga specific libraries        gcc270-base
  339. guide/            Docs in AmigaGuide(tm) format        gcc270-doc
  340. man/            this is the root for tons of man pages    gcc270-doc
  341. bin/            this is /bin, and contains all         gcc270-c
  342.             binaries of this distribution that    gcc270-c++
  343.             are meant to be directly invoked by    gcc270-utils
  344.             the user (contrary to the executables
  345.                  in lib/gcc-lib/, that are meant to be
  346.             invoked by a driver program like gcc)
  347. lib/            normal (not base relatives) libraries    gcc270-inclib
  348. lib/libm020/        normal 68020 libraries            gcc270-inclib
  349. lib/libb/        base relatives libraries        gcc270-inclib
  350. lib/libb/libm020/    base relatives using 68020 libraries    gcc270-inclib
  351. lib/libnix/        Non-ixemul libraries            gcc270-inclib
  352. lib/libm020/libnix/    Non-ixemul 68020 libraries        gcc270-inclib
  353. lib/libb/libnix/    Non-ixemul base relatives libraries    gcc270-inclib
  354. lib/libb/libm020/libnix    Non-ixemul base relatives 68020 libs    gcc270-inclib
  355. lib/gcc-lib/        home of compilers called by gcc        gcc270-c
  356.                                 gcc270-c++
  357.                                 gcc270-objc
  358. ixpipe/            a pipe handler needed by the library    gcc270-base
  359. libs/            ixemul.library                gcc270-base
  360. rexx/            ARexx wrappers for gcc and g++        gcc270-base
  361. src-patches/        source patches                gcc270-diffs
  362. geninline/        Perl scripts to generate inline headers    gcc270-inclib
  363.             and -lamy glue
  364.  
  365. ==============
  366. Inline-Headers
  367. ==============
  368.  
  369. Since I'm not able to redistribute Amiga header files, you will have to get
  370. them directly from Commodore, unless you're an official registered Amiga
  371. developer. You can also find Development Kit on FreshFish CD-Roms.
  372. In order to generate inline-headers, follow these steps (provided Amiga
  373. headers and fd files are in os-include). If you are compiling for Kickstart
  374. 3.1 or less, you don't have to generate them, inlines are provided with
  375. the distribution.
  376.  
  377. 1) First method:
  378.  
  379. CLI> stack 100000
  380. CLI> Assign INCLUDE: GCC:os-include
  381. CLI> Assign FD: INCLUDE:fd
  382. CLI> Makedir INCLUDE:inline
  383. CLI> cd USR:bin/geninline
  384. CLI> gen31
  385.  
  386. This will create all inline-headers. If you have 2.0 headers, use gen20
  387. instead, if you have 3.0, use gen30, if you have 6.4, send it to me ;-)
  388.  
  389. NOTE: perl scripts do not handle correctly AmigaDOS include files, which
  390. seems to mean they are somewhat broken. If someone could work on this...
  391.  
  392. 2) Second method:
  393.  
  394. Use fd2inline, which you can find on Aminet in dev/gcc.
  395.  
  396. ===============
  397. Amiga Libraries
  398. ===============
  399.  
  400. Starting from 2.6.0 an AmigaDOS compliant library is provided, thanks to
  401. libnix authors (Matthias Fleischer and Gunther Nikl).
  402.  
  403. Anyway if you want to rebuild one, there are two methods:
  404.  
  405. 1) Using hunk2gcc; the AmigaDOS object converter made by Markus Wild. To
  406. achieve this, simply grab a copy of latest amiga.lib (from Commodore
  407. Development Kit) and make a new directory where you want your converted
  408. object files to go, cd into it, and enter
  409.  
  410.   hunk2gcc amiga.lib [..further libs if you like..]
  411.  
  412. This generates an a.out object file for every program unit present in the
  413. hunk file (in this case, from amiga.lib).
  414.  
  415. As the final step convert all those files into an a.out style library by
  416. issuing:
  417.  
  418.   ar qc libamiga.a obj.*
  419.   ranlib libamiga.a
  420.  
  421. The ranlib run builds a symbol table in the archive, and makes accesses to
  422. the library much faster.
  423.  
  424. 2) Creating a libamiga.a library with libnix is fairly easy, but takes some
  425. time. Just decompress sources.lha from libnix distribution and run a
  426. 'make libamiga.a'.
  427.  
  428. NOTE:
  429.  
  430. As long as you make no AmigaDOS specific calls, you can create a dummy
  431. library using:
  432.  
  433.   cat "int dummy;" >dummy.c
  434.   gcc -c dummy.c
  435.   ar crv libamiga.a dummy.o
  436.   mv libamiga.a gcc:lib
  437.  
  438. A small libamiga.a (dummy) is also provided with libnix.
  439.  
  440. ====================
  441. Upgrade Installation
  442. ====================
  443.  
  444. - You will at first have to decide if you want to keep your existing
  445.    GCC compiler or not. This might sound silly, but it is in fact possible.
  446.  
  447.   - I want to keep older GCC compiler
  448.  
  449. CLI> cd GNU:lib
  450. CLI> rename libgcc.a GNU:lib/gcc-lib/mc68000-cbm-amigados/2.6.3
  451. (note: replace 2.6.3 with your GCC version)
  452. CLI> rename libb/libgcc.a GNU:lib/gcc-lib/mc68000-cbm-amigados/2.6.3/libb
  453. CLI> rename libm020/libgcc.a GNU:lib/gcc-lib/mc68000-cbm-amigados/2.6.3/libm020
  454. CLI> cd GNU:bin
  455. CLI> rename gcc gcc-2.6.3
  456. CLI> rename gccv gccv-2.6.3
  457.  
  458.   - I don't care about previous versions
  459.  
  460. CLI> delete GNU:lib/gcc-lib/mc68000-cbm-amigados/2.6.3 all quiet
  461.  
  462. Proceed then to "Distribution Installation" below, for
  463. mandatory archives only.
  464.  
  465. =========================
  466. Distribution Installation
  467. =========================
  468.  
  469. NOTE: you MUST at least unpack gcc270 base, inclib and c parts. Other
  470. archives are optional.
  471.  
  472. - You need first to create a directory gnu on your hard-disk and unarchive
  473. first part:
  474.  
  475. CLI> cd place_with_lot_of_space
  476. CLI> makedir gnu
  477. CLI> lha x gcc270-base.lha
  478.  
  479. - Now you have to append gnu/s/user-startup to your s:user-startup file
  480. (replace Devel:GNU by your own gnu path). Execute it in order to get new
  481. assigns:
  482.  
  483. CLI> execute gnu/s/user-startup
  484.  
  485. - Copy gnu/envarc to ENVARC:
  486.  
  487. CLI> copy gnu/envarc/#? ENVARC:
  488.  
  489. - GCC libraries and headers:
  490.  
  491. CLI> lha x gcc270-inclib.lha
  492.  
  493. - C-compiler is needed so unarchive C compiler part (Users with
  494. accelerated Amigas can unarchive gcc270-c-020 part instead) :
  495.  
  496. CLI> lha x gcc270-c.lha  (or gcc270-c-020)
  497.  
  498. - If you want to have GCC documentation on-line, unarchive doc part:
  499.  
  500. CLI> lha x gcc270-doc.lha
  501.  
  502. - If you want to do C++, unarchive C++ part (Users with
  503. accelerated Amigas can unarchive gcc270-c++-020 part instead) :
  504.  
  505. CLI> lha x gcc270-c++.lha (or gcc270-c++-020)
  506.  
  507. Please note that 68020 versions have '.020' extension in GNU:bin.
  508.  
  509. - If you want to do Objective-C, unarchive Objective-C part (Users with
  510. accelerated Amigas can unarchive gcc270-objc-020 part instead) :
  511.  
  512. CLI> lha x gcc270-objc.lha (or gcc270-objc-020)
  513.  
  514. - If you want additional utilities (recommended for Unix compatibility),
  515. unarchive utils part:
  516.  
  517. CLI> lha x gcc270-utils.lha
  518.  
  519. - If you want all utilities documentation on-line, unarchive utils-doc
  520. part:
  521.  
  522. CLI> lha x gcc270-utilsdoc.lha
  523.  
  524. - Because some programs are normally links to others, please run script:
  525.  
  526. CLI> sh /gnu/s/restorelinks
  527.  
  528.   Or if you don't want to use makelink but rather copy file, run script:
  529.  
  530. CLI> sh /gnu/s/restorelinks copy
  531.  
  532. - If you want to rebuild all distribution, you'll have to unarchive
  533. diff part:
  534.  
  535. CLI> lha x gcc270-diffs.lha
  536.  
  537. - If you want to build Postscript files for GCC documentation, unarchive
  538. texinfo part:
  539.  
  540. CLI> lha x gcc270-texi.lha
  541.  
  542. - Now skip to next paragraph and happy compiling!
  543.  
  544. NOTE:  new version of ixemul.library is provided, make sure you don't have
  545. another copy somewhere which may conflict with GCC.
  546.  
  547. =============================
  548. Your first C program with GCC
  549. =============================
  550.  
  551. What about a nice Hello World ?
  552.  
  553.     #include <stdio.h>
  554.  
  555.     main()
  556.     {
  557.       printf("Hello World!\n");
  558.     }
  559.  
  560. This was pretty simple ;-) Now we have to compile it.
  561. There's a lot of options in GCC but the simplest way to compile this would
  562. be:
  563.  
  564. CLI> gcc -o hello hello.c
  565.  
  566. Simple?
  567.  
  568. Here's more options.
  569.  
  570. Target processor for Motorola family:
  571. You can compile plain 68000 code, 68020, 68030, 68040, 68881 (have a look at
  572. GCC documentation, either in info or AmigaGuide format, chapter Invoking
  573. GCC/SubModel Options/M680X0 Options for Motorola specific compilation flags).
  574.  
  575. CLI> gcc -m68020 -m68881 -o hello hello.c
  576.  
  577. This will compile your programs using 68020 code and direct calls to
  578. math-processor, and will link with accelerated libraries, located in
  579. GCC:lib/lib020.
  580.  
  581. Optimization:
  582. Either you don't want optimization, or you can provide -O, which will
  583. optimize your code, or if you really want top optimization, use -O2 flag
  584. (for more discussion about optimization, read info or AmigaGuide doc chapter
  585. Invoking GCC/Optimize Options). There's now even a -O3 optimization option,
  586. which will go even further.
  587.  
  588. CLI> gcc -O2 -o hello hello.c
  589.  
  590. You'll never have a "Hello World" program running so fast ;-)
  591.  
  592. Code generation:
  593. Perhaps you want to generate resident programs.
  594. Flag is -resident, at compile and link stage.
  595.  
  596. CLI> gcc -resident -o hello hello.c
  597.  
  598. Of course you can mix all options, resulting in:
  599.  
  600. CLI> gcc -O2 -m68020 -m68881 -resident -o hello hello.c
  601.  
  602. This will make a 68020+68881 executable highly optimized and resident.
  603.  
  604. IMPORTANT:
  605. If you only use AmigaDOS functions or you don't want to use ixemul for
  606. philosophical reasons, you can get rid of ixemul.library with:
  607.  
  608. CLI> gcc -noixemul -o foobar foobar.c
  609.  
  610. provided you have libnix distribution (included with 2.6.0 and up
  611. distributions).
  612.  
  613. ================
  614. Ixemul vs Libnix
  615. ================
  616.  
  617. Starting with 2.6.1 version of AmigaDOS-GCC, two C libraries are provided.
  618.  
  619. First one is using ixemul.library Amiga shared-library at run-time. This
  620. library makes it possible to easily convert Unix(tm) programs to AmigaDOS,
  621. and made for example possible GCC on AmigaDOS. Have a look at ixemul.guide
  622. for further informations.
  623.  
  624. Second one is an ANSI-C compliant library which is better suited for
  625. AmigaDOS specific development, thus not using any Unix specific routines.
  626. Libnix is a static (i.e. link) library for GCC 2.3.3 or above.
  627. It's not a replacement for ixemul.library (though it's possible to
  628. recompile most of the GCC environment with libnix) but a good thing
  629. for Amiga specific development on GCC:
  630.  
  631. * It's mostly compatible to SAS's way of handling things, i.e.
  632.   you get even an automatic shared library opening feature and
  633.   some other things you may miss in ixemul.library.
  634.   This also means it's ANSI compliant.
  635.  
  636. * It doesn't need any shared libraries other than normal Amiga OS ones.
  637.  
  638. * It is not copyrighted by the FSF. Therefore you neither need
  639.   to include sources nor objects together with your executable.
  640.   (read the GLGPL _before_ flaming on this statement)
  641.  
  642. * And it's short! I was able to compile a 492 byte 'hello, world'
  643.   using normal main.
  644.  
  645. * It uses OS 2.0 features whenever necessary.
  646.  
  647. Note that you can develop AmigaDOS specific programs with ixemul.library,
  648. but at the cost of an extra 200 kB of memory taken by shared library.
  649.  
  650. To cut it short:
  651.  
  652. Use ixemul.library for porting Un*x programs, libnix for compiling
  653. Amiga-only programs and GCC becomes one of the best Amiga compilers.
  654.  
  655. ===============================
  656. Redirection with ixemul.library
  657. ===============================
  658.  
  659. A common problem seen with AmigaDOS-GCC is bad redirection to stderr.
  660.  
  661. The fact is that ixemul.library takes stderr from the pr_CES field
  662. in the process structure. The field was added in 2.0. If the field
  663. is not set, then ixemul uses stdout, instead. The trouble is that this
  664. field must be set by the shell, and the only shell that does so is
  665. WShell!
  666.  
  667. The rationale behind ixemul.library working this way is that
  668. "run <NIL: >NIL: cmd" will detach your process from the terminal, so
  669. that you can close the initial CLI window after startup.
  670.  
  671. In any case, there is a workaround for the problem that was posted to the
  672. list a while back: compile your main program using the -Dmain=mymain
  673. option, then link with stderrfix.o to provide the actual main that will
  674. do the magic that creates an stderr stream that is different from
  675. stdout. Along with the C version a C++ version is included and was used to
  676. compile groff.
  677.  
  678. Thanks to Kriton Kyrimis for this explanation and patch.
  679. stderr fixes can be found in GNU:stderrfix (srcs-) and GNU:lib (.o files).
  680.  
  681. =====
  682. ARexx
  683. =====
  684.  
  685. The provided ARexx scripts have been contributed by Loren J. Rittle.
  686. If you like ARexx, they're an alternate way of calling GCC. They
  687. automatically make sure you're using a large enough stack setting, and
  688. enable you to compile C++ programs with less obscure options.
  689.  
  690. ===============
  691. Gcc versus gccv
  692. ===============
  693.  
  694. gccv stands for a gcc using vfork() to spawn a new process, and then calling
  695. the new execve() function in ixemul.library to call its subcompilers. Gcc
  696. continues to using the more system friendly RunCommand() function in
  697. dos.library to start subcompilers. Gccv has the advantage of being able to
  698. work with interprocess pipes, thus (provided you have the memory ;-)), you're
  699. able to do
  700.  
  701.     gccv -pipe your_program.c
  702.  
  703. causing the preprocessor (cpp), the C-compiler (cc1) and the assembler (as)
  704. to run at the same time, passing intermediate files through internal pipes
  705. instead of using temporary files.
  706.  
  707. As long as you don't want that feature (OK, playing with certain make tools
  708. also requires gccv) you're safe using gcc.
  709.  
  710. ==========
  711. Stack size
  712. ==========
  713.  
  714. You need to have a stack size of 50000 in order to compile with GCC. This
  715. should be enough for most projects. Note than while recompiling GCC with
  716. itself it has taken more than 300 kB of stack. Stack usage can grow due to
  717. source complexity.
  718. Don't be afraid of it.
  719.  
  720. To set the stack size, see the AmigaDOS Command 'stack'.
  721.  
  722. To use ar and/or ranlib, 50 kB is the minimum acceptable stack. You should
  723. have a much larger stack, if you use larger libraries.
  724.  
  725. Starting with 2.6.3 a new environment variable, GCCSTACK, enables gcc to
  726. read this variable and set stack upon startup. Thus now no need to set stack
  727. to huge values, only gcc/ld/cpp/cc1#? will automatically set new stack,
  728. according to GCCSTACK variable.
  729.  
  730. Simply commit a:
  731.     setenv GCCSTACK value
  732. to set gcc stack to value.
  733.  
  734. Benefits: Huge memory savings.
  735.  
  736. ========
  737. Priority
  738. ========
  739.  
  740. Starting also with 2.6.3 a new environment variable, GCCPRIORITY, let you
  741. specify a default process priority for GNU compiler. Setting it to -1 enable
  742. your Amiga to do something else while compiling :-)
  743.  
  744. ===========
  745. C++ headers
  746. ===========
  747.  
  748. With AmigaDOS it makes no difference whether a name has capital or
  749. lower-case letters in names when finding files (i.e. it is case
  750. insensitive), you'll certainly run into problems with some headers,
  751. including String.h and normal string.h. My suggestion for now is to add to
  752. C++ "faulty" header file name an "_" in front of it, thus String.h would
  753. become _String.h. Sorry for the inconvenience. (Thanks to Dirk Nehring for
  754. reminding me about this annoying "feature").
  755.  
  756. =======
  757. Patches
  758. =======
  759.  
  760. Includes:
  761.  
  762.     Jorg Hoehle
  763. hoehle@inf-wiss.uni-konstanz.de
  764.  
  765. There is a conflict between the Amiga and the UNIX definition of the
  766. timeval structure.  Markus Wild proposed in GCC233 to patch the Amiga
  767. devices/timer.h file so that it loads the UNIX sys/time.h file (and
  768. thus tons of other files) (see os-include/devices/timer.mwild.path). I
  769. suggest that sys/time.h and devices/timer.h be modified to detect each
  770. other and use whichever structure was declared first (see
  771. os-include/devices/timer.jch.patch). The supplied include/sys/time.h
  772. file works this way.  You can apply the patches with the program patch
  773. or by hand. The original devices/timer.h file is copyrighted by
  774. Commodore-Amiga and not included, but here is the patch:
  775.  
  776. + #ifndef _SYS_TIME_H_
  777. + /* Use whatever was included first, standard (sys/time.h) or Amiga
  778. +  * includes (jch). */
  779.   struct timeval {
  780.       ULONG tv_secs;
  781.       ULONG tv_micro;
  782.   };
  783. + #else
  784. + #define tv_secs  tv_sec
  785. + #define tv_micro tv_usec
  786. + #endif
  787.  
  788. The sys/types.h defined BPTR causing conflicts with Amiga includes. I
  789. removed the BPTR definition from sys/types.h and sys/proc.h. In
  790. GCC233, there was no such definition either.
  791.  
  792. I moved the ixemul.h file from include/ to the ixemlib/library/
  793. directory. The ixemlib/ directory could contain the ixemul.library
  794. sources. In the ixemul source tree, ixemul.h is found in the library/
  795. directory.  Furthermore I patched it so that it is now able to compile
  796. a working ixconfig. It was broken (because of the broken ixemul.h) in
  797. GCC252/3/4.  It previously worked in GCC233 but didn't provide the -e
  798. option. The ixemlib/library/version.h is an empty fake. I don't have a
  799. newer ixemul.h file.
  800.  
  801. There's yet another minor patch I'd like to suggest:
  802. *** include/stdlib.h.orig    Mon Aug 10 15:28:54 1992
  803. --- include/stdlib.h    Fri Dec 09 17:12:38 1993
  804. ***************
  805. *** 72,76 ****
  806. --- 72,80 ----
  807.   void    *calloc __P((size_t, size_t));
  808.   div_t     div __P((int, int));
  809. + #if 0
  810.   void volatile exit __P((int));
  811. + #else /* new ANSI-C interpretation */
  812. + typedef void exit_t __P((int)); volatile exit_t exit;
  813. + #endif
  814.   void     free __P((void *));
  815.   char    *getenv __P((const char *));
  816.  
  817. ===============
  818. Ld (GNU linker)
  819. ===============
  820.  
  821. Starting from 2.5.8 release, ld behaviour over symbols has changed. Default
  822. is now to strip all symbols from generated executable ONLY if environment
  823. variable LDSTRIP is set (to whatever you want). Otherwise, '-s' flag will
  824. strip symbols, as usual.
  825. Also packing of uninitialized data will be done automatically if LDSHORTDATA
  826. is set (to whatever you want).
  827. Ld also knows about -chip and -fast keywords, gcc will soon handle them
  828. directly.
  829. Ld is using now flavours, which are generated depending on gcc flags:
  830.  
  831. Gcc option    Flavor passed to ld
  832. -m68020        -fl libm020
  833. -noixemul    -fl libnix
  834. -resident    -fl libb
  835.  
  836. Thus ld when searching for libraries, adds those flavours to the library
  837. search path, in alphabetical order. Normal search path is /gnu/lib, and
  838. if for example you want to compile using -m68020 -noixemul ld will look
  839. for libgcc.a in:
  840.     /gnu/lib/libm020/libnix
  841. first, then it will reduce flavours, one by one, if it can't find required
  842. library in flavour's expanded path. This means that it will try to find
  843. libgcc.a in:
  844.     /gnu/lib/libm020
  845. and in  /gnu/lib/. Because libgcc.a exists in /gnu/lib/libm020, ld will take
  846. this one.
  847.  
  848. There is as for now 8 possibilities:
  849.  
  850.     Flavors        Search path
  851. libb libm020 libnix
  852.  0      0      0    /gnu/lib/            normal
  853.  0      0      1    /gnu/lib/libnix/        non-ixemul
  854.  0      1      0    /gnu/lib/libm020/        normal 68020
  855.  0      1      1    /gnu/lib/libm020/libnix/    non-ixemul 68020
  856.  1      0      0    /gnu/lib/libb/            baserel
  857.  1      0      1    /gnu/lib/libb/libnix/        baserel non-ixemul
  858.  1      1      0    /gnu/lib/libb/libm020/        baserel 68020
  859.  1      1      1    /gnu/lib/libb/libm020/libnix/    baserel 68020 non-ix
  860.  
  861. Using this approach makes adding flavours pretty easy, if someone wants for
  862. example to add 68881 libraries, a new flavour will have to be created,
  863. libm881, and thus the maximum flavour search path level would be:
  864. /gnu/lib/libb/libm020/libm881/libnix, which can be translated to English as:
  865. "I want a base-relative library compiled using Motorola 68020 and coprocessor
  866. 68881, not using ixemul.library".
  867.  
  868. =====================
  869. GCC and its "pragmas"
  870. =====================
  871.  
  872. From Gunther Nikl:
  873.  
  874. Accessing operating-system functions on the Amiga requires to pass arguments
  875. in specific processor registers. C, however, uses a different calling
  876. convention: It pushes all arguments in reverse order onto the stack, calls
  877. the function and finally removes the arguments from the stack by simply
  878. correcting the stack pointer.
  879. One solution to interface C and the calling convention for the system
  880. functions are so called "glue"-functions that convert arguments passed on
  881. the stack into the OS-function convention. These glue routines are located
  882. for all system libraries in a link library named libamiga.a. Obviously this
  883. method is inefficient. Most Amiga C-compilers have the capability of in-line
  884. calls to OS functions using a C language extension "#pragma". The format of
  885. a pragma statement and file names differ from compiler to compiler. GCC
  886. supports in-line calls too but not with pragmas. the GCC solution is based
  887. on the fact that GCC is able to integrate small functions into the caller.
  888. This method is known from C++ as "inlining". Thus functions that are
  889. declared "inline" (preferable in conjunction with the keyword static or
  890. extern but see the next chapter) get integrated. As you can see writing
  891. programs that compile with several compilers and use its capability of making
  892. in-line calls to libraries is a tricky thing.
  893.  
  894. To get programs more portable between Amiga C-compilers a new set of include
  895. files would be helpful that hide the different methods for in-line calls
  896. from the user. These files are located in a drawer called proto e.g.
  897. "proto/exec.h". Instead of writing (only an example!):
  898.  
  899.     #include <clib/exec_protos.h>
  900.     #ifdef __GNUC__
  901.     #include <inline/exec.h>
  902.     #endif
  903.  
  904. now the following should be used:
  905.  
  906.     #include <proto/exec.h>
  907.  
  908. to achieve the same result! Nice, isn't it? The general rule for the all
  909. files is:
  910.  
  911.     #include <proto/xxx.h>
  912.  
  913. with "xxx" replaced with the first part of a clib proto-headers name e.g.
  914. "exec_protos.h" becomes "exec.h"
  915.  
  916. In general each file first includes its function prototype header then the
  917. compiler specific "pragma" header and finally declares the library base
  918. extern. The GCC files are in the following format:
  919.  
  920.     (1) include some C= headers to prevent errors with GCC
  921.     (2) include the function prototypes from the clib drawer
  922.     (3) include the inline header if this is not disabled and if
  923.             optimizing
  924.     (4) declare the library base extern if its not disabled
  925.  
  926. Step 3 will only be executed if GCC is optimizing. Otherwise the compiler
  927. won't integrate any function. Even when optimizing it could be not desired
  928. to include the inline header because it requires some amount of memory and
  929. the compile time enlarges significantly. Therefore step 3 can be disabled
  930. with:
  931.  
  932.     - a define on the command line "-D__NOINLINES__"
  933.             or
  934.     - a define before the proto headers are included "#define __NOINLINES__"
  935.  
  936. Declaring the library base as an external variable can disabled with a
  937. define in the same way. The define is called "__NOLIBBASE__". This define
  938. can be useful if its not desired to have the library base declared extern.
  939.  
  940. Using the new proto headers has some advantages then using the clib and
  941. inline files by itself:
  942.  
  943.     (1) better compatibility with SAS/C. It should be much easier to compile
  944.         programs developed for SAS/C with GCC - almost ;) no need to adjust
  945.         includes
  946.     (2) almost ;) optimal code because depending on the optimization level
  947.         the best suited include set will be used
  948.     (3) internal compiler specific requirements are hidden from the user
  949.  
  950. For the exec.library the proto header has one additional goodie: it
  951. "implements" SAS/C "_USEOLDEXEC_". Defining this forces to evaluate the
  952. absolute address 4 every time the library base for the exec.library is
  953. required. In this case no global library base is necessary but it must be
  954. noted that programs compiled with this option enabled can have performance
  955. problems because AbsExecBase is located in Chip-Memory. Be aware: if using
  956. _USEOLDEXEC_ its *NOT* legal to declare or define SysBase! If you do so
  957. strange things may happen ... Please note that some function in libamiga.a
  958. require a global "SysBase" so that those functions cannot be used.
  959.  
  960. Some problems still remain but these restrictions come from the inline
  961. technique. Library bases have to be global due to the nature of the
  962. inlines. SAS/C, however, is able to use local variables or structure
  963. elements as library bases. In this case the library bases has to be made
  964. global for GCC.
  965.  
  966. ==============
  967. Inline headers
  968. ==============
  969.  
  970. One major advantage of GCC is its ability to integrate simple functions into
  971. the caller. To direct the compiler to inline a function the keyword "inline"
  972. in combination with "static" or "extern" can be used. Previous version of the
  973. inlines used static in the definition. This had the effect that functions
  974. compiled to assembler if optimization is disabled. The new inline headers use
  975. extern definitions. Functions defined inline and extern can be considered as
  976. macros. That means the definition is only used for inlining thus requiring
  977. linking with a library containing stubs.
  978.